﻿
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- saved from url=(0014)about:internet -->
<html xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:mssdk="winsdk" xmlns:script="urn:script" xmlns:build="urn:build" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="Description" content="Using Client Objects"/>
<meta name="MSHAttr" content="PreferredSiteName:MSDN"/>
<meta name="MSHAttr" content="PreferredLib:/library/windows/hardware"/>
<title>Using Client Objects</title>

<meta name="MS-HAID" content="Engine_DG_4902f2ee-669d-4691-b52b-bf48e4e84f40.xml"/>


<link rel="STYLESHEET" type="text/css" HREF="../common/backsdk4.css"/>





<style>
html,div { margin: 0; padding: 0;}

body {
	padding: 0px;
	margin: 0px;
	overflow: auto;
	height: 100%;
}

#winchm_template_button{
	float: right;
	width: 93px;
	top: 7px;
	position: relative;
	text-align: right;
	right: 5px;
	height: auto;
}

#winchm_template_top{
	padding: 0px;
	margin: 0px;
	border-bottom: 1px solid #9B9B9B;
	background-color: #B1CEFE;
}

#winchm_template_navigation{
	margin: 0px;
	padding-top: 7px;
	padding-left: 7px;
	padding-bottom: 3px;
	padding-right: 0px;
	font-size: 8.5pt;
	font-family: Arial, Helvetica, sans-serif;
	font-weight: normal;
	color: #585858;
}

#winchm_template_title{
	margin: 0px;
	padding-top: 4px;
	padding-left: 7px;
	padding-bottom: 7px;
	padding-right: 0px;
	font-size: 18px; 
	font-family: Verdana, Geneva, sans-serif;
	color: #363636;
}

#winchm_template_content{
	margin-top: 20px;
	margin-left: 15px;
	margin-bottom: 20px;
	margin-right: 15px;
	width: auto  !important;
	width: 100%;
}

#winchm_template_footer{
	border-width: 1px;
	border-color: #B1CEFE;
	border-top-style: solid;
	margin-top: 15px;
	margin-left: 15px;
	margin-bottom: 20px;
	margin-right: 15px;
	padding-top: 7px;
	padding-left: 0px;
	padding-bottom: 0px;
	padding-right: 0px;
	font-family: arial, helvetica, sans-serif;
	font-size: 8.5pt;
	color: #696969;
	width: auto;
	text-align: left;
}


#winchm_template_container{
	margin: 0px;
	padding: 0px;
	position: static;
	padding-bottom: 3px;
	overflow: auto;
	background-color: #FFFFFF;
}


@media print
{
#winchm_template_container{
	position: static;	
	margin: 0px;
	padding: 5px;
	
	width: auto;
	height: auto;
	overflow: auto;
}
#winchm_template_button{
visibility:hidden;
}
}

#winchm_template_navigation A:link	{text-decoration: none; color:#004080}
#winchm_template_navigation A:visited  {text-decoration: none; color: #004080}
#winchm_template_navigation A:active {text-decoration: none; color: #004080 }
#winchm_template_navigation A:hover {text-decoration: none;color: #0080FF}

A:link	{text-decoration: underline; color:#0033CC}
A:visited  {text-decoration: underline; color: #0033CC}
A:active {text-decoration: underline; color: #0033CC }
A:hover {text-decoration: underline;color: #FF0000;}
</style>
<script type="text/javascript">
function isMobile(){
Agent = window.navigator.userAgent;
if (Agent.indexOf("iPhone")>=1 || Agent.indexOf("iPad")>=1 || Agent.indexOf("iPod")>=1 || Agent.indexOf("Android")>=1){
return true;
}else{
return false;	
}

}
function d_onresize(){
if (window.navigator.userAgent.indexOf("MSIE")>=1){
document.getElementById('winchm_template_container').style.pixelWidth = document.body.offsetWidth - 3;
document.getElementById('winchm_template_container').style.pixelHeight = document.body.offsetHeight - document.getElementById('winchm_template_top').offsetHeight - 4;
}
document.getElementById('winchm_template_container').style.top = document.getElementById('winchm_template_top').offsetHeight + 'px';
}

function d_onbeforeprint(){
document.getElementById('winchm_template_container').style.width = 'auto';
document.getElementById('winchm_template_container').style.height = 'auto';
}

function d_onafterprint(){
d_onresize();
}

if(!isMobile()){

window.onload = d_onresize;
window.onresize = d_onresize;
window.onbeforeprint = d_onbeforeprint;
window.onafterprint = d_onafterprint;

document.write("<style>\n");
document.write("body {overflow: hidden;}\n");
document.write("#winchm_template_container {position: absolute;overflow: auto;top : 0px;right: 0px;bottom: 0px;left: 0px;}\n");
document.write("</style>\n");
}

</script>
</head>
<body><script language="JavaScript" type="text/JavaScript">
function syn(){
if(parent.nav.tree){
 if(parent.nav.tree.loaded){
  parent.nav.tree.selectNode(207);
 }else{
  setTimeout("syn()",500);
}
  }else{
  setTimeout("syn()",500);
  }}
if(parent!=self){
  setTimeout("syn()",100);
}else{
  parent.location.href = "../../index.htm?page=debugger/using_client_objects.htm";
}
originalOnload = window.onload;
if(originalOnload==null){
window.onload = function(){parent.contentLoaded = true;};
}else{
window.onload = function(){originalOnload();parent.contentLoaded = true;};
}
</script> 


<div id="winchm_template_top">
	<div id="winchm_template_button"><A href="interacting_with_the_engine.htm" title="Previous topic"><img id="winchm_template_prev" alt="Previous topic" src="../template2/btn_prev_n.gif" border="0"></a><A href="using_callback_objects.htm" title="Next topic"><img id="winchm_template_next" alt="Next topic" src="../template2/btn_next_n.gif" border="0"></a></div>
	<div id="winchm_template_navigation">Help &gt; 
<A href="introduction6.htm">Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)</A> &gt; <A href="debugging_resources.htm">Debugging Resources</A> &gt; <A href="debugger_engine_and_extension_apis.htm">Debugger Engine and Extension APIs</A> &gt; <A href="using_the_debugger_engine_api.htm">Using the Debugger Engine API</A> &gt; <A href="debugger_engine_api_overview.htm">Debugger Engine API Overview</A> &gt; <A href="interacting_with_the_engine.htm">Interacting with the Engine</A> &gt; </div>
	<div id="winchm_template_title">Using Client Objects</div>
</div>
<div id="winchm_template_container">
	<div id="winchm_template_content"><div id="mainSection"><p>For an overview of the role of client objects in interacting with the debugger engine, see <a href="#Bookmark195">Client Objects</a>.</p>
<p>In general, a client's methods may be called only from the thread in which the client was created. Typically, methods called from the wrong thread will fail immediately.  The notable exception to this rule is the method <a href="#Bookmark296"><b>CreateClient</b></a>; this method may be called from any thread, and returns a new client that can be used in the thread from which it was called.  Other exceptions are documented in the reference section.</p>
<p>A string describing a client object is returned by the method <a href="#Bookmark307"><b>GetIdentity</b></a> or can be written to the engine's output stream using <a href="#Bookmark318"><b>OutputIdentity</b></a>.</p>
<h3><a id="com_interfaces"></a><a id="COM_INTERFACES"></a>COM Interfaces</h3>
<p>The debugger engine API contains several COM like interfaces; they implement the <b>IUnknown</b> interface.</p>
<p>The interfaces described in the section <a href="#Bookmark242">Debug Engine Interfaces</a> is implemented by the client (though not necessarily at the latest version).  You may use the COM method <b>IUnknown::QueryInterface</b> to obtain each of these interfaces from any of the others.</p>
<p>The clients implement the <b>IUnknown</b> COM interface and use it for maintaining reference counts and interface selection. However, the clients are not registered COM objects.  The method <b>IUnknown::AddRef</b> is used to increment the reference count on the object, and the method <b>IUnknown::Release</b> is used to decrement the reference count.  When <b>IUnknown::QueryInterface</b> is called, the reference count is incremented, so when a client interface pointer is no longer needed <b>IUnknown::Release</b> should be called to decrement the reference count.</p>
<p>The reference count will be initialized to one when the client object is created using <a href="#Bookmark240"><b>DebugCreate</b></a> or <a href="#Bookmark238"><b>DebugConnect</b></a>.</p>
<p>See the Platform SDK for more information about when reference counts should be incremented and decremented.</p>
<p><b>IUnknown::QueryInterface</b>, <b>DebugCreate</b>, and <b>DebugConnect</b> each take an interface ID as one of their arguments.  This interface ID can be obtained using the <b>__uuidof</b> operator. For example:</p>
<div class="code"><span codelanguage=""><table>
<tr>
<th></th>
</tr>
<tr>
<td>
<pre>IDebugClient * debugClient;
HRESULT Hr = DebugCreate( __uuidof(IDebugClient), (void **)&amp;debugClient );</pre>
</td>
</tr>
</table></span></div>
<div class="alert"><b>Important</b>  The IDebug* interfaces such as <a href="#Bookmark786"><b>IDebugEventCallbacks</b></a> interface, although COM like, are not proper COM APIs. Calling these interfaces from managed code is an unsupported scenario. Issues such as garbage collection and thread ownership, lead to system instability when the interfaces are called with managed code.</div>
<div> </div></div></div>	
	<div id="winchm_template_footer">Copyright &copy; 2019. All rights 
reserved. (To change the copyright info, just edit it in template.)</div>
</div>

</body>
</html>
